home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / VLIB103.ARJ / VIEWLIB.MAN < prev    next >
Text File  |  1992-06-08  |  21KB  |  756 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                        ViewLib
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                    Reference Manual
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.                          Copyright 1992, DB/Soft Publishing.
  31.                                  All rights reserved.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                                 Printed in the U.S.A.
  41.  
  42.                              Version 1.00, first printing
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.           Copyright________________________________________________________
  51.  
  52.           This software is protected under  United States Copyright Law and
  53.           International Treaty provisions.  DB/Soft Publishing reserves all
  54.           rights to ViewLib except for the following:
  55.  
  56.           A limited license is hereby granted allowing you use and evaluate
  57.           ViewLib for up  to 30 days.  You may also distribute unregistered
  58.           copies of  ViewLib  in its  entirety  to any  parties  interested
  59.           provided no  modification of  the  files in  the ViewLib  archive
  60.           occurs.    The  maximum  transaction  related  to  selling  media
  61.           containing unregistered copies of ViewLib  (eg Shareware vendors)
  62.           may not exceed $10.00.   Conversion to a more  convenient archive
  63.           format  is allowed.    All other  uses  of ViewLib  violate  this
  64.           license and are hereby expressly disallowed.
  65.  
  66.                         Copyright 1992, by DB/Soft Publishing,
  67.                                  All Rights Reserved.
  68.  
  69.                     3200 Truxel Rd #199, Sacramento, CA 95833 USA
  70.  
  71.                               Telephone: (916) 927-6951
  72.  
  73.                                  BBS: (916) 927-2349
  74.  
  75.           Limited Warranty_________________________________________________
  76.  
  77.           DB/Soft Publishing  grants no warranties, express  or implied, by
  78.           statute  or otherwise,  regarding this  software and  its related
  79.           materials, their fitness for any purpose, their quality, or their
  80.           merchantability.  In  no way shall  DB/Soft Publishing be  liable
  81.           for  any  special, consequential,  other  damages  for breach  of
  82.           warranty.
  83.  
  84.           This Statement  shall be  construed, interpreted and  governed by
  85.           the laws of the State of California.
  86.  
  87.           This  warranty will be replaced by a limited 90-day warranty that
  88.           covers the diskette, software and documentation upon registration
  89.           of ViewLib.
  90.  
  91.  
  92.           Registering ViewLib______________________________________________
  93.  
  94.           ViewLib  is an example  of software marketed  under the Shareware
  95.           concept.  The premise is simple:  you may evaluate  ViewLib for a
  96.           reasonable period  of time  (30 days  maximum)  during which  you
  97.           decide if  it is  a library  worth owning  and using  for viewing
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.           files  from within your applications.   If so,  you must register
  106.           ViewLib, using order.doc for  ordering information.  If, after  a
  107.           reasonable evaluation period, you decide not to register ViewLib,
  108.           you then must discontinue its use.
  109.  
  110.           This  provides me  with a way  to market  software with  very low
  111.           advertising  overhead, which  results in  a price  savings passed
  112.           directly on to you.  And, it provides you with a chance to 'play'
  113.           with my product and decide if it meets your needs. 
  114.  
  115.           As an incentive to speed the registration process, only the small
  116.           memory  model  of ViewLib  is  distributed  as shareware.    Upon
  117.           registration, you  will receive all the  available memory models:
  118.           small, medium,  compact  and  large,  for both  Borland  C++  and
  119.           Microsoft C.
  120.  
  121.  
  122.           Getting Help_____________________________________________________
  123.  
  124.           There are several ways of contacting the author, Jeff Dunlop, for
  125.           technical assistance if you get stuck.  From cheapest and slowest
  126.           to most expensive and fastest:
  127.  
  128.                - Fidonet's SHAREWRE or C_ECHO echoes
  129.  
  130.                - ILink's Shareware conference
  131.  
  132.                - Fidonet netmail at 1:203/16
  133.  
  134.                - Compuserve mail at 72147,3055
  135.  
  136.                - Internet at 72147.3055@compuserve.com
  137.  
  138.                - The DB/Soft Online at (916) 927-2349
  139.  
  140.                 - By mail at 3200 Truxel Rd #199 Sacramento CA 95833
  141.  
  142.           The best method of contacting  the author depends on the type  of
  143.           assistance you need.   If it's a rather complicated  problem, you
  144.           will  probably be far better  served if you  prepare a message in
  145.           advance  and upload  it  with a  source  example to  the  DB/Soft
  146.           Online.  We can then test it and offer suggestions.  If it's just
  147.           a question or suggestion about ViewLib capabilities, the ILink or
  148.           Fidonet conferences  will work best.   Fidonet netmail privileges
  149.           can be difficult to  get, but offer excellent timeliness  at very
  150.           low connect time.  Check your local Fidonet BBS if interested.
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.                                   Table of Contents
  159.  
  160.  
  161.                Chapter 1 Introduction .................................. 2
  162.                     Features ........................................... 2
  163.                     Requirements ....................................... 2
  164.                     Getting Started .................................... 2
  165.  
  166.                Chapter 2 Function Reference ............................ 4
  167.                     vlLister ........................................... 4
  168.                     vlGetVidMode ....................................... 6
  169.                     vlGetVidBase ....................................... 7
  170.                     vlGetCols .......................................... 7
  171.                     vlGetRows .......................................... 8
  172.                     vlIsDV ............................................. 8
  173.                     vlIsEgaVga ......................................... 9
  174.                     vlIsShift .......................................... 9
  175.                     vlIsRShift ......................................... 9
  176.                     vlIsLShift ......................................... 10
  177.                     vlIsMono ........................................... 10
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.                                           1
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.           Chapter 1 
  214.  
  215.           Introduction_____________________________________________________
  216.  
  217.  
  218.           Features_________________________________________________________
  219.  
  220.           ViewLib provides an excellent means  to providing report and file
  221.           viewing from  within  your C  applications.   Some  of  ViewLib's
  222.           features include:
  223.  
  224.               -     View any size file
  225.  
  226.               -     Resize and move the view window at will
  227.  
  228.               -     Completely define the color of the text and border.  
  229.  
  230.               -     Completely  define  the  characters  that  compose  the
  231.                     border.
  232.  
  233.               -     Define the initial size of the View window.
  234.  
  235.               -     ViewLib can  operate with as  little as  30k free  ram,
  236.                     which  is  released  back   to  your  application  when
  237.                     finished.
  238.  
  239.               -     Desqview, EGA  and VGA are all  detected and respected.
  240.                     In DesqView, the shadow buffer is used to avoid  bleed-
  241.                     through to other tasks. 
  242.  
  243.           Requirements_____________________________________________________
  244.  
  245.           You  must own either a Microsoft  or Borland C compiler.  ViewLib
  246.           should  be compatible  with  most if  not  all of  the  compilers
  247.           produced by  these two  companies, and  with any  other companies
  248.           that  produces compatible compilers  (Watcom comes to  mind).  If
  249.           you require ViewLib's functionality with an unsupported compiler,
  250.           the  only solution  is to  purchase the  source code  (please see
  251.           order.doc for details).
  252.  
  253.           Getting Started__________________________________________________
  254.  
  255.           ViewLib  can be linked into  any application just  like any other
  256.           library.    Therefore, you  should  copy  vl*.lib into  the  same
  257.           directory  that you  keep your  other  .lib files  in.   The file
  258.  
  259.  
  260.                                           2
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.           vlibbcs.lib  is for  Borland compilers,  and vlibmscs.lib  is for
  269.           Microsoft compilers.
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.                                           3
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.           Chapter 2
  324.  
  325.           Function
  326.           Reference________________________________________________________
  327.  
  328.  
  329.           vlLister_________________________________________________________
  330.  
  331.              Usage: int vlLister(char  *FileSpec, int  x1, int y1,  int x2,
  332.                     int  y2,  unsigned   char  Foreground,  unsigned   char
  333.                     Background, unsigned BufSize, BORDER *BorderInfo);
  334.  
  335.              Prototype in:  vlib.h
  336.  
  337.              Description:   vlLister  displays  in  the coordinates  x1, y1,
  338.                             x2,  y2 the  filename  passed.   The coordinates
  339.                             are 0-based.   The minimum  allowed buffer  size
  340.                             is eight kilobytes (8092  bytes).  The suggested
  341.                             optimum buffer size is  also 8k.   The only time
  342.                             that  it might  be  beneficial to  work  with  a
  343.                             larger buffer is  in the case of reading a  file
  344.                             on  a  floppy  drive.    The  valid  colors  for
  345.                             Background (defined in vlib.h) are as follows:
  346.  
  347.                             BLACK, BLUE, GREEN, CYAN,  RED, MAGENTA,  BROWN,
  348.                             LIGHTGREY
  349.  
  350.  
  351.                             The valid colors  for Foreground are any of  the
  352.                             colors valid for Background, plus:
  353.  
  354.                             DARKGREY,   LIGHTBLUE,  LIGHTGREEN,   LIGHTCYAN,
  355.                             LIGHTRED, LIGHTMAGENTA, YELLOW, WHITE
  356.  
  357.  
  358.                             The user-accessable fields of BorderInfo are:
  359.  
  360.                             bd_enable:  Set to  TRUE if  a border is  to be
  361.                                         displayed.   If  set to  FALSE, all
  362.                                         other values are ignored.
  363.  
  364.                             b_string:   A string  describing the characters
  365.                                         that  are  used   to  construct   a
  366.                                         border.  Any character value in the
  367.                                         extended   IBM  character   set  is
  368.  
  369.  
  370.                                           4
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.                                         valid.  The string  "┌─┐│└─┘" would
  379.                                         make a box similar to:
  380.                                         ┌──────┐
  381.                                               │      │
  382.                                               └──────┘
  383.  
  384.                             Foreground: The    colors   valid    for   text
  385.                                         foreground are valid here as well.
  386.  
  387.                             Background: The    colors   valid    for   text
  388.                                         background are valid here as well.
  389.  
  390.  
  391.           Return value:  Upon  successful  completion, vlLister  returns 0.
  392.                          The following error codes are defined in vlib.h:
  393.  
  394.                        VLIB_ARGERR
  395.                        VLIB_DOSERR
  396.                        VLIB_ALLOCERR
  397.  
  398.              Example:
  399.  
  400.              #include "vlib.h"
  401.  
  402.              void main(void)
  403.              {
  404.  
  405.                BORDER BorderInfo = {{TRUE}, {"┌─┐│└─┘"}, {YELLOW}, {BLUE}};
  406.  
  407.                vlLister("file.txt",  1, 1,  78,  23, YELLOW,  BLUE, 0x2000,
  408.                &bd_info);
  409.              }
  410.  
  411.           The behavior  of vlLister depends on whether BorderInfo.bd_enable
  412.           is TRUE or FALSE.   If the border is disabled, then it is assumed
  413.           that the calling  function has  prepared a custom  border and  so
  414.           border resizing/window moving is disabled as well.  If the border
  415.           is enabled, then the base of the border  has the following string
  416.           displayed:
  417.  
  418.                   PgUp PgDn Home End Esc
  419.  
  420.           These are a subset of the allowed  keystrokes.  The complete list
  421.           of legal keystrokes is:
  422.  
  423.           Home:   Display from the top of the file
  424.  
  425.                                           5
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.           End:    Display the end of the file
  434.  
  435.           PgUp:   Display  the  previous  page  (varies  according  to   the
  436.                   current window size.
  437.  
  438.           PgDn:   Display the  next page  (varies according  to the  current
  439.                   window size
  440.  
  441.           Down:   Display the next line.
  442.  
  443.           Up:     Display the previous line.
  444.  
  445.           Right:  Shift the display left 10 columns.
  446.  
  447.           Left:   Shift the display right 10 columns.
  448.  
  449.           RShift-Right:  Lengthen the window to the right one column.
  450.  
  451.           RShift-Left:   Shorten the window to the left one column.
  452.  
  453.           RShift-Dn:     Lengthen the window down one row.
  454.  
  455.           RShift-Up:     Shorten the window up one row.
  456.  
  457.           LShift-Right:  Move the window right one column.
  458.  
  459.           LShift-Up:     Move the window up one row.
  460.  
  461.           LShift-Left:   Move the window left one column.
  462.  
  463.           LShift-Dn:     Move the window down one row.
  464.  
  465.  
  466.           vlGetVidMode_____________________________________________________
  467.  
  468.              Usage: unsigned char vlGetVidMode(void);
  469.  
  470.              Prototype in:  vlib.h
  471.  
  472.              Description:   vlGetVidMode returns the current  video mode  as
  473.                             reported by Bios.
  474.  
  475.              Return Value:  Refer  to a  MS-Dos  technical  reference manual
  476.                             for  the possible  return  values of  Bios video
  477.                             modes and their meanings.
  478.  
  479.  
  480.                                           6
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.              Example:
  489.  
  490.              #include <stdio.h>
  491.              #include "vlib.h"
  492.  
  493.              void main(void)
  494.              {
  495.                printf("Current video mode is %d\n", vlGetVidMode());
  496.              }
  497.  
  498.  
  499.           vlGetVidBase_____________________________________________________
  500.  
  501.              Usage: unsigned vlGetVidbase(void);
  502.  
  503.              Prototype in:  vlib.h
  504.  
  505.              Description:   vlGetVidBase returns  the segment of the current
  506.                             video display buffer.
  507.  
  508.              Return Value:  Usually, b000  will be  returned for  monochrome
  509.                             display,  and b800  for  all others.    However,
  510.                             DesqView  shadow  buffers may  contain different
  511.                             addresses on some platforms.
  512.  
  513.              Example:
  514.  
  515.              #include <stdio.h>
  516.              #include "vlib.h"
  517.  
  518.              void main(void)
  519.              {
  520.                printf("The  current  video  ram  base  address  is  %ud\n",
  521.                vlGetVidBase());
  522.              }
  523.  
  524.  
  525.           vlGetCols________________________________________________________
  526.  
  527.              Usage: int vlGetCols(void);
  528.  
  529.              Prototype in:  vlib.h
  530.  
  531.              Description:   vlGetCols   determines  the  number  of  columns
  532.                             currently being displayed.
  533.  
  534.  
  535.                                           7
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.              Return Value:  Most systems will  return 80 columns.   However,
  544.                             DesqView windows  defined at unusual sizes  will
  545.                             be  detected,  as  will  132-column (and  other)
  546.                             displays.
  547.  
  548.              Example:
  549.  
  550.              #include <stdio.h>
  551.              #include "vlib.h"
  552.  
  553.              void main(void)
  554.              {
  555.                printf("The monitor is  currently displaying %d  columns\n",
  556.                vlGetCols());
  557.              }
  558.  
  559.  
  560.           vlGetRows________________________________________________________
  561.  
  562.              Usage: int vlGetRows(void);
  563.  
  564.              Prototype in:  vlib.h
  565.  
  566.              Description:   vlGetRows   determines   the  number   of   rows
  567.                             currently being displayed.
  568.  
  569.              Return Value:  Most  systems  will return  25  rows.   However,
  570.                             DesqView windows defined at  unusual sizes  will
  571.                             be detected,  as will 43-column, 50-column  (and
  572.                             other) displays.
  573.  
  574.              Example:
  575.  
  576.              #include <stdio.h>
  577.              #include "vlib.h"
  578.  
  579.              void main(void)
  580.              {
  581.                printf("The  monitor  is  currently  displaying  %d rows\n",
  582.                vlGetRows());
  583.              }
  584.  
  585.  
  586.           vlIsDV___________________________________________________________
  587.  
  588.              Usage: int vlIsDV(void);
  589.  
  590.                                           8
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.              Prototype in:  vlib.h
  599.  
  600.              Description:   vlIsDV  determines whether DesqView is installed
  601.                             and active.
  602.  
  603.              Return Value:  If  DesqView  is  active,  vlIsDV returns  TRUE;
  604.                             otherwise, FALSE is returned.
  605.  
  606.              Example:
  607.  
  608.              #include <stdio.h>
  609.              #include "vlib.h"
  610.  
  611.              void main(void)
  612.              {
  613.                printf("DesqView %s active\n", vlIsDV() ? "is" : "is not");
  614.              }
  615.  
  616.  
  617.           vlIsEgaVga_______________________________________________________
  618.  
  619.              Usage: int vlIsEgaVga(void);
  620.  
  621.              Prototype in:  vlib.h
  622.  
  623.              Description:   vlIsEgaVga  determines whether an enhanced color
  624.                             adapter is installed.
  625.  
  626.              Return Value:  If  an   EGA  or  VGA   adapter  is   installed,
  627.                             vlIsEgaVga  returns  TRUE; otherwise,  FALSE  is
  628.                             returned.
  629.  
  630.              Example:
  631.  
  632.              #include <stdio.h>
  633.              #include "vlib.h"
  634.  
  635.              void main(void)
  636.              {
  637.                printf("An EGA or VGA monitor %s installed.\n", vlIsEgaVga()
  638.                ? "is" : "is not");
  639.              }
  640.  
  641.  
  642.           vlIsShift
  643.           vlIsRShift
  644.  
  645.                                           9
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.           vlIsLShift_______________________________________________________
  654.  
  655.              Usage: int vlIsLshift(void);
  656.                     int vlIsRshift(void);
  657.                     int vlIsShift(void);
  658.  
  659.              Prototype in:  vlib.h
  660.  
  661.              Description:   vlIsShift,  vlIsLShift and vlIsRShift return the
  662.                             status  of the  shift  keys as  appropriate  for
  663.                             each function.
  664.  
  665.              Return Value:  If  the appropriate shift key  is being pressed,
  666.                             the function  returns TRUE;  otherwise, FALSE is
  667.                             returned.
  668.  
  669.              Example:
  670.  
  671.              #include <stdio.h>
  672.              #include "vlib.h"
  673.  
  674.              void main(void)
  675.              {
  676.                printf("A shift key %s being pressed.\n", vlIsShift() ? "is"
  677.                : "is not"); 
  678.              }
  679.  
  680.  
  681.           vlIsMono_________________________________________________________
  682.  
  683.              Usage: int vlIsMono(void);
  684.  
  685.              Prototype in:  vlib.h
  686.  
  687.              Description:   vlIsMono determines  if the  current video  mode
  688.                             is monochrome.
  689.  
  690.              Return Value:  If  the   current  video  mode  is   monochrome,
  691.                             vlIsMono   returns  TRUE;  otherwise,  FALSE  is
  692.                             returned.
  693.  
  694.              Example:
  695.  
  696.              #include <stdio.h>
  697.              #include "vlib.h"
  698.  
  699.  
  700.                                           10
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.              void main(void)
  709.              {
  710.                printf("The monitor %s monochrome video mode.\n", vlIsMono()
  711.                ? "is" : "is not");
  712.              }
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.                                           11
  756.